Prepare your Raspberry PI
Image your Raspberry PI
Use the Raspberry PI Imager software to download and install the RPI software to your SD card.
Instructions for doing this are on the site itself. You will need an SD card and some way to write to that from your computer. Alternatively you may already have a pre-installed RPI SD card. That should work as well.
Here is what the imager looks like currently on OSX.
For the device choose the Raspberry PI Zero 2W
For the Operating System choose the Raspberry PI OS (64-Bit)
You should not need to apply any customizations to the configuration. Be aware that this will totally wipe any existing contents on the SD card so only do this when you are ready!
Make sure that the verify step works after the image has been created. If it doesn't work try re-running the installation.
Boot up your PI machine
Put the SD card into the SD slot in the RPI and attach the Mini HDMI cable and connect it to a monitor. Be sure to push the HDMI cable all the way in - the connection is tight and if you don't get it all the way in then it will not detect your monitor.
If you have a wired keyboard or mouse connect these also using the appropriate USB adaptors and/or a hub.
Alternatively you can connect a bluetooth keyboard and mouse during the boot process. In this mode the RPI will pause during the boot process and ask you to disconnect and reconnect the power - when it comes back up it will initiate a pairing mode for you to connect your keyboard and mouse.
Once connected you can configure the country, language and timezone.
Next create a user account. For this project please create an account called clock. You can add additional accounts later but the software is going to assume a clock user.
- Set username: clock
- Set a password: can be anything - but suggest "clock" as it is easy to remember!
Then connect to your WIFI network. I sometimes saw issues with this and so if you are not seeing your WIFI network then you can skip this here and connect to it later.
Next select the browser you want to use as default. This doesn't matter as far as the clock project is concerned.
If you were able to connect to the WIFI network then the RPI will try to update the software at this point. Just be aware that this may take quite a while to do! I prefer to skip this and then do the update once the machine is running as you get a bit more feedback on the progress.
Now restart the machine to get into the desktop environment.
Boot into the RPI desktop environment
You should now be into the RPI desktop environment.
If you did not connect to your WIFI in the previous step then do so now. You can click on the icon in the top right and follow the instructions here
If you did not do the updates during the previous step this would also be a good time to do those. The system should alert you to the updates once you have connected to the internet. There should be an icon in the system tray in the top right of the screen.
The RPI might be fairly unresponsive during the updates and they may take 20+ minutes to complete.
Download the Source Code
You are now ready to download the code which will configure and run your clock.
Start a Terminal window on the RPI using the icon in the top left of the screen or by using the start menu and selecting Accessories ... Terminal.
In the terminal window type the commands below. Make sure you are in the home directory of the clock user.
> cd /home/clock
> git clone https://github.com/paulpaterson/wordclock
This will connect to github and download the repository containing all the source code for the clock and the configuration script.
You do not need a github account to download the code.
Run the Installation Configuration Script
Once the github code has been downloaded you are ready to run the installer script. This will get your RPI ready to drive the clock.
It performs the following actions automatically:
1. Creates a backup of the RPI config files in case you need to restore
2. Configures the PI to boot into the console rather than window environment
3. Turns on the SPI interface for controlling the LED lights
4. (optionally) turns on the SSH interface so you can remotely monitor it
5. (optionally) configures a Real Time Clock to provide a backup clock in case the power goes out
6. Configures a Python environment to run the clock code, and its dependencies
7. Creates the services needed to run the clock automatically when it powers up
8. Configures a web application to allow remote configuration of clock parameters
9. (optionally) configures the default Shell to use FISH rather than BASH
To run the script you use the script wordclock/scripts/installer_script.sh
To install the default configuration just use:
> cd wordclock
> ./scripts/installer_script.sh
...
There are some additional options you can specify on the command line based your needs. Each of these adds parameters to the installer script.
Hardware options
To also configure the system to use the Real Time Clock (RTC) add --rtc to the command line
To add the configuration for the Camera module (if you want to be able to have the clock automatically connect to a Wifi network) add --camera to the command line. Please note this adds a lot of files to be configured - it is not an issue but will take a lot longer to install and looks a bit worrying how much stuff it is downloading!
Recommended Software options
To enable SSH acces to your RPI add --ssh. You will then be able to log in using SSH using the clock username.
To give your RPI a specific name add --name MYNAME to the command line.
You can give the RPI a fixed IP address, which makes it easier to find on the network. Just add --ip 192.168.1.XXX where XXX is a number. Suggested values should be >200 to avoid clashing with another device on your network.
Optional Software options
You can install FISH as the default Shell for the RPI if you like that instead of BASH. Just add --fish to the command line.
An example fully specified command line is below:
> cd wordclock
> ./scripts/installer_script.sh --rtc --ssh --fish --camera --name MyRPI --ip 192.168.1.200
...
If everything went well then you can reboot your RPI to get everything working. Even if you suspect something didn't go right then still reboot and jump to the Validation and Troubleshooting step.
> sudo reboot now
...
NOTE It is safe to run the installer script as many times as you want, changing options to meet whatever you are wanting.
Reboot the PI
Once the PI reboots you should be at the command line prompt rather than the desktop environment.
You can login here, using the clock username and password you entered earlier.
Alternatively, if you added SSH in the installer step, you can login using SSH with the IP address from the installation step.
If everything has gone well and you have the clock hooked up to the hardware then everything should be working now!
Validation and Troubleshooting
If the clock is not running, or just as an additional check, you can run the validation script which will take a look at the clock and see if everything seems to be set up OK. If something is wrong then this may point you in the right direction.
> cd /home/clock/wordclock
> ./scripts/validate.sh
